
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections;

using Swaf;


namespace Swaf.Gui
{
	public enum GuiType {Unknown, WinForm, Browser, GDI, AspNet};

	/// <summary>
	/// The base interface for visual GUI elements (the model from the MVC design pattern) and
	/// GUI Processes within the framework.</summary>
	public interface IGuiElement : IDescriptive
	{
		string Id{get;}
	}

	/// <summary>
	/// The base interface for visual GUI elements that display their user interface by generating
	/// HTML and responding to browser events.</summary>
	/// <remarks>
	/// Implementors of this interface use HTML DOM objects to represent thier user interface.
	/// Theoretically it is possible that the HTML DOM implementation is something other then
	/// Internet Explorer, such as the Mozilla browser (the Netscape browser gone open source), 
	/// but in reality all of the framework implementations of this interface make serious
	/// use of the Internet Explorer specific implementation of the HTML DOM.</remarks>
	public interface IGuiWidget : IGuiElement
	{
		GuiType WidgetType{get;}
		/// <summary>
		/// Should return the minimum size for a gui element of some kind.
		/// </summary>
		/// <param name="parentContext">Each GUI Environment has its own way of calculating a minimum size
		/// which may require a helper object of some kind to do the work.  For example, in WinForms, to truely
		/// calculate a size, a Graphics object is needed.</param>
		/// <returns></returns>
		NumericPair MinimumSize(object parentContext);

		/// <summary>
		/// The GUI environment specific element that is represented by this sizing.
		/// </summary>
		object Ctl {get;}

		/// <summary>
		/// The name of the property that is used to get/set a "value" for the widget when appropriate.
		/// </summary>
		/// <remarks>This is an optional property that helps describe how to use the widget to display
		/// values.  Implementing this property properly will allow the widget to be used as a biz obj
		/// field editor in dynamic IBizObjDisplay implementations.</remarks>
		string ValueProperty{get;}

		void sizePositionTo(Rect r);

		/// <summary>
		/// Indicates that a batch of calls will be made to this GUI element that would cause 
		/// updates of its display to occur and that it should defer updating its display
		/// until <c>enableUpdate</c> is called.</summary>
		void disableUpdate();

		/// <summary>
		/// Indicates that the GUI element should refresh its display and go back to updating
		/// its display as it needs to.</summary>
		void enableUpdate();

		/// <summary>
		/// Until a GuiElement is given an <c>ILocation</c> ,it will be unable to display
		/// itself.  Call show to display the element at a given location.</summary>
		/// <param name="location"></param>
		void show(ILocation location);

		/// <summary>
		/// Indicates the element should release its <c>ILocation</c> reference.  Without
		/// the location, this element will not be able to display any information.</summary>
		void hide();

		/// <summary>
		/// In order to support generic interaction with a GUI element, an element's individual
		/// events are exposed through this so that an observer can register for events with
		/// the element without having to first cast the element to a specific type.  
		/// </summary>
		/// <param name="eventName">Text that contains the name of the event on the element</param>
		/// <param name="observer">The delegate to callback when the given event occurs.  The actual
		/// type of this delegate needs to match up with the specific event being attached to or a
		/// runtime error will occur.</param>
		void addObserver(string eventName, Delegate observer);

		/// <summary>
		/// Removes the observer from the given event on the element. See the 
		/// <see cref="System.Framework.Gui.IHtmlElement.addObserver">addObserver</see> method
		/// for more information about this pair of methods.</summary>
		/// <param name="eventName">Text that contains the name of the event to be removed from</param>
		/// <param name="observer">The delegate to remove.</param>
		void removeObserver(string eventName, Delegate observer);

		ILayoutManager ParentLayout{get;set;}

	}

}